home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 051-075 / scopedisk62 / pipe203 / pipe.doc < prev    next >
Text File  |  1995-03-19  |  5KB  |  145 lines
  1.  
  2. PIPE.DOC    Version 2.00        Matthew Dillon
  3.  
  4.     Matthew Dillon
  5.     891 Regal Rd.
  6.     Berkeley, Ca. 94708
  7.  
  8.     ..ihnp4|ucbvax|dillon
  9.     dillon@ucbvax.berkeley.edu
  10.  
  11.  
  12.     I have completely re-written my PIPE: handler from scratch.  The PIPE:
  13. device now supports bi-directional connections through a single file-handle,
  14. dynamic buffer sizing, signaling capability, and several other options for
  15. supporting virtual terminals (i.e. slaving a CLI).
  16.  
  17.     It is upward compatible with the old version in that you still
  18. redirect from PIPE:name and to PIPE:name (with the same name) to make
  19. a pipe.
  20.  
  21.     The PIPE: normally has a 4K buffer associated with it, but you should
  22. not count on an application not blocking when writing to it unless you give
  23. the PIPE: the /n option (example:  pipe:a/n).  this option allows the
  24. buffer to grow to any size.
  25.  
  26.  *  --------------------------- Warning, technical discussion follows ------
  27.  *
  28.  *  A given PIPE path has a notion of MASTER and SLAVE.  The MASTER portion
  29.  *  refers to the named PIPE when openned with modes 1006 (NEWFILE).  The
  30.  *  SLAVE portion refers to the named PIPE when openned with modes 1005
  31.  *  (OLDFILE).    Most applications of the PIPE use only a single direction.
  32.  *
  33.  *  However, some applications require data transmission over both
  34.  *  directions.  For instance, you can specify:
  35.  *
  36.  *  NEWCLI pipe:a    (see example below for more practical use with a CLI)
  37.  *
  38.  *  The CLI is the SLAVE.  You can then write a driving program by openning
  39.  *  the pipe mode 1006.  You must read and write using that mode (i.e. if
  40.  *  you openned with 1005 and did a read, you would simply be reading the
  41.  *  data you sent with the 1006 filehandle rather than what the CLI is
  42.  *  giving back to us).
  43.  *
  44.  *  The pipe supports several options using the following naming format:
  45.  *
  46.  *  PIPE:name[/options]
  47.  *
  48.  *  options:    t    Read()'s block if no data is available, but return
  49.  *            as soon as data is available (not necc. on newline
  50.  *            boundries).  Thus, a minimum of one byte is returned
  51.  *            until you get to the End Of the File, in which case
  52.  *            0 is returned.    I.E. make it look sortof like a
  53.  *            terminal.
  54.  *
  55.  *        n    simple way of saying "no maximum" for the dynamic
  56.  *            buffering on writes.  Basically, any writes you
  57.  *            do to this filehandle always return immediately
  58.  *            unless you run out of memory.
  59.  *
  60.  *        b#    Set the maxmimum dynamic buffer size (default 4096)
  61.  *            Can be set arbitrarily high.  Writes will not
  62.  *            block unless the dynamic buffer size excedes this
  63.  *            value or you run out of memory.
  64.  *
  65.  *            Only buffer room for the actual amount of queued data
  66.  *            is allocated.
  67.  *
  68.  *        s#    When read data is available on file handle, signal
  69.  *            my task with signal number # (0..31).
  70.  *
  71.  *            THIS ALSO EFFECTS READS: If no data is currently
  72.  *            available, a Read() will return 0.  Read()s can
  73.  *            now return less than the requested number of bytes
  74.  *            as in the 't' option.
  75.  *
  76.  *            -1 is returned on EOF instead of 0.
  77.  *
  78.  *        q    Query if the other end of this PIPE: is active.
  79.  *            .e.g. if you open with modes 1005(SLAVE), the
  80.  *            open will succede if there is something connected
  81.  *            to the MASTER part, and visa versa.  Otherwise,
  82.  *            the open fails.
  83.  *
  84.  *  EXAMPLES:    pipe:a        -normal pipe
  85.  *        pipe:a/b16384    -use a slightly larger write buffer.
  86.  *        pipe:a/s31    -have the PIPE handler signal your
  87.  *                 task when read data becomes available
  88.  *                 on this filehandle.
  89.  *
  90.  *  EXAMPLE:    Slaving a NEWCLI:
  91.  *
  92.  *    Execute("newcli pipe:name/t",0L,0L);
  93.  *    fh = Open("pipe:name/tns31", 1006);
  94.  *
  95.  *    -signal will come in whenever read data becomes available on fh.
  96.  *    -you should Read() all available data.    Check for a -1 return
  97.  *     value indicating that the slave closed his connection.
  98.  *
  99.  *    -write to the same filehandle to send data to the slave.  The
  100.  *     slave gets the data immediately due to the '/t' option even
  101.  *     if it may be less than his pending Read().
  102.  *
  103.  *     We pass the 'n' option to ensure our writes do not block
  104.  *     (be careful!) to prevent a lockout situation.
  105.  *
  106.  *    NOTE NOTE NOTE NOTE NOTE.  A CLI does not recognize EOF's
  107.  *    (i.e. you closing your filehandle).  (A) You can re-open the
  108.  *    same file handle at some later time and continue talking to the
  109.  *    CLI.  (B) You MUST send an 'ENDCLI' to actually cause the CLI
  110.  *    to quit.  With this example, you can recognize when the CLI has
  111.  *    closed it's connection when your Read() returns -1.
  112.  *
  113.  *  Additions for 2.02 from 2.01:
  114.  *    high and low water marks implemented for better efficiency
  115.  *
  116.  *
  117.  
  118.  
  119.  
  120.     EXAMPLE:    Slaving a NEWCLI:
  121.  
  122.     Execute("newcli pipe:name/t",0L,0L);
  123.     fh = Open("pipe:name/tns31", 1006);
  124.  
  125.     -signal will come in whenever read data becomes available on fh.
  126.     -you should Read() all available data.    Check for a -1 return
  127.      value indicating that the slave closed his connection.
  128.  
  129.     -write to the same filehandle to send data to the slave.  The
  130.      slave gets the data immediately due to the '/t' option even
  131.      if it may be less than his pending Read().
  132.  
  133.      We pass the 'n' option to ensure our writes do not block
  134.      (be careful!) to prevent a lockout situation.
  135.  
  136.     NOTE NOTE NOTE NOTE NOTE.  A CLI does not recognize EOF's
  137.     (i.e. you closing your filehandle).  (A) You can re-open the
  138.     same file handle at some later time and continue talking to the
  139.     CLI.  (B) You MUST send an 'ENDCLI' to actually cause the CLI
  140.     to quit.  With this example, you can recognize when the CLI has
  141.     closed it's connection when your Read() returns -1.
  142.  
  143.  
  144.  
  145.